HAL RCC migration: List of applicable concepts

This section provides information about the HAL RCC applicable concepts, followed by the HAL CRS applicable concepts.

Concepts for RCC

Concept	Description
Replace HAL_RCC_OscConfig with unitary APIs for individual RCC oscillators
Replace HAL_RCC_ClockConfig with unitary APIs for clock source configuration
Provide unitary configuration APIs for PLL management	This concept applies only STM32 series with a PLL module in the RCC peripheral.
Peripheral-specific APIs for clock source selection	New APIs have been introduced to select the peripherals kernel clock source, and the global HAL_RCCEx_PeriphCLKConfig function has been removed.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL RCC driver, and equivalent services are ensured through the LL APIs.
RCC clock macros converted to inline functions
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL RCC driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros are used to check the parameters and state of the HAL RCC driver.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL RCC header file remains and all macros, define statements, and functions from hal_rcc_ex.h have been moved to hal_rcc.h.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	This is not applicable for single instance peripherals across all STM32 series.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including RCC instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL RCC functions start with HAL_RCC. All HAL RCC enumerations and structures start with hal_rcc.

---

Other HAL RCC changes

Concept	Consideration
Remove all the dependencies with FLASH and GPIO HAL driver	Flash latency should be configured corresponding to the system clock frequency out of RCC APIs. GPIO PIN configuration should be managed in the application when configuration of MCO or LSCO output clock is needed.
Replace force/release function by reset function only	Add HAL_RCC_PPP_Reset function will call force reset and release reset function.
Provide peripherals Low Power enabling APIs for specific mode	Depending on the supported Low Power mode for a peripheral (according to Reference manual RCC and PWR Chapters), provide HAL_RCC_LP_PPP_Enable/DisableClockInLowPowerMode() APIs where LowPower can be: Sleep, Stop.
Add APIs to check oscillators enabled & ready states	Add APIs to check oscillator enabled state HAL_RCC_<OSC>_IsEnabled() and Add APIs to check oscillator ready state HAL_RCC_<OSC>_IsReady().

---

Concepts for CRS

Concept	Notes
Separation of initialization and configuration functions	The HAL CRS is a newly introduced driver. In HAL1, CRS functionality was implemented as a set of functions integrated within the HAL RCC driver. In HAL2, it has been refactored into a dedicated, standalone HAL CRS driver. Therefore, we applied the following concept: The HAL_RCCEx_CRSConfig() has been split into separate initialization and configuration functions: HAL_CRS_Init(): initializes the handle and links it to a CRS instance. HAL_CRS_SetConfig(): sets the basic configuration to enable the use of the CRS instance.
Removal and conversion of init structure to configuration structure	The initialization structure has been removed and moved into hal_crs_config_t configuration structure.
Unitary configuration APIs	New APIs are available to set and get CRS features.
Introduction of HAL user data set/get APIs	Add HAL User Data Set/Get APIs: HAL_CRS_SetUserData() HAL_CRS_GetUserData()
HAL implementation with LL inline functions	HAL RCC APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL RCC define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL RCC driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL API status returns	Update HAL CRS functions to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	Redesign the error handling mechanisms within the HAL to improve the detection, reporting, and handling of errors.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL RCC driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Remove stm32tnxx_ll_ppp.c files	No stm32tnxx_ll_crs.c file in HAL2.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including RCC instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL CRS functions start with HAL_CRS. All HAL CRS enumerations and structures start with hal_crs.

Other HAL CRS changes

Concept	Consideration
Provide a standalone HAL CRS driver applying the generic HAL2 architecture rules.	For more details, please refer to: Concepts for CRS.